In general, all the procedures that users perform using the applications of the service providers involve the intervention of multiple Web services belonging to different systems. From the perspective of user support, auditing or even accounting, it can be useful to distinguish all the activity deriving from a particular procedure that the user is performing. This can be achieved by propagating a correlation identifier across the different systems involved in the procedure so that this identifier appears in all the events logged by the applications themselves and the systems that interact with them. TRIDENT supports that the applications include an external correlation identifier in the service request.

When an external correlation identifier is not used, TRIDENT returns the correlation identifier assigned internally to the operation (the internal correlation identifier) to the application. It can be useful for the application to log this internal correlation identify in case of error to facilitate the diagnosis of problems.

Syntax of the External Correlation Identifier
Including an External Correlation Identifier in the Requests Sent to TRIDENT
Including the Correlation Identifier in the Browser’s Redirects
Obtaining the Internal Correlation Identifier from the TRIDENT Responses

Syntax of the External Correlation Identifier

The external correlation identifier is a character string that identifies an instance of a procedure of interest to the service provider, which we want to correlate to the invoked operations of TRIDENT. We recommend that the identifier be a random value that does not include any sensitive data on the user to which the service request refers. For example:

896bf2112c0d48b79c19812a

The correlation identifier can have up to 255 characters and contain any visible ASCII character except the vertical bar (|).

If TRIDENT receives a correlation identifier in the service request, it includes it in the external_trace_id field of the events of all the operations associated to these requests.

Additionally, the identifier can be concatenated with a name for the operation in which the request to the TRIDENT service forms part of using the vertical bar (|) character. This name must statically and concisely identify a procedure that is statistically of interest to the service provider. For example:

896bf2112c0d48b79c19812a|TermsAcceptanceSignature

The operation name can have up to 255 characters and contain any visible ASCII character except the vertical bar (|).

If TRIDENT receives the name of an operation in a service request, it includes it in the external-origin and from parameter of the first level event corresponding to the request.

Including an External Correlation Identifier in the Requests Sent to TRIDENT

In requests sent to the REST APIs of TRIDENT, such as those for obtaining of an OAuth 2.0 access token or deleting a signature process on a document, the external correlation identifier can be included in the HTTP X-Request-ID header.

Example

This example shows how to send an OAuth access token request that includes an external correlation identifier in the X-Request-ID header. Ellipses and line breaks have been included to facilitate reading.

POST /trustedx-authserver/oauth/corp/token HTTP/1.1
Host: trustedx.demo.com:443
Authorization: Basic ZGVtb2FwcDpkZW1vZGVtbw==
X-Request-ID: 896bf2112c0d48b79c19812a
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
  
grant_type=authorization_code&
    redirect_uri=https://www.demoapp.com/oauth/back&
    code=4515...e0ba

Including the Correlation Identifier in the Browser’s Redirects

In protocols that redirect the browser to TRIDENT, such as those for obtaining OAuth 2.0 authorizations, SAML 2.0 Web single sign-on or the execution of document signing processes, it is not possible to include the X-Request-ID header because the browser cannot send headers when following a redirect. In these cases, the external correlation identifier can be included in the x_request_id parameter of the URL to which the browser is redirected.

Example

This example shows an OAuth authorization request that includes an external correlation identifier in the x_request_id parameter. The user's browser made this HTTP request as a result of a redirect from the application. Ellipses and line breaks have been included to facilitate reading.

GET /trustedx-authserver/oauth/corp?response_type=code&
                                    client_id=demoapp&
                                    state=3dd9...8cd4&
                                    x_request_id=896bf2112c0d48b79c19812a&
                                    redirect_uri=https://www.demoapp.com/oauth/back HTTP/1.1
Host: trustedx.demo.com:8082

Obtaining the Internal Correlation Identifier from the TRIDENT Responses

If the service provider does not include an external correlation identifier in the calls to TRIDENT, the internal correlation identifier assigned by TRIDENT can be obtained. This is done by querying the X-Correlation-ID header of the response message. This internal correlation identifier is different for each TRIDENT operation invoked.

Example

This example shows a response from the OAuth access token issue service that includes an internal correlation identifier in the X-Correlation-ID header.

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
X-Correlation-ID: wnXmmQLZbRf0KHRr8rrP
 
{
   "access_token" : "a2b4...6daf",
   "token_type" : "Bearer",
   "expires_in" : 120
}

Note

Currently it is only possible to obtain the internal correlation identifier in the responses to REST calls.